View RM0060_8986178.PDF datasheet online --- IC-ON-LINE

Datasheet File OCR Text:

copyright ? 2011 zilog ? , inc. all rights reserved. www.zilog.com zaura ? rf wireless technology zaura rf wireless library programmer?s reference manual RM006003-1011
RM006003-1011 zaura rf wireless library programmer?s reference manual do not use this product in life support systems. life support policy zilog?s products are not auth orized for use as critical components in life support de vices or systems without the express prior written approval of the president and general counsel of zilog corporation. as used herein life support devices or systems are devices which (a) are intended for surgical implant into the body, or (b) support or sustain life and whose failure to perform when properly used in accordance with instru ctions for use provided in the labeling can be reasonably expected to result in a si gnificant injury to the user. a critical component is any component in a life support device or system whose failure to perform can be reasonably expected to cause the failure of the life suppor t device or system or to affect its safety or effectiveness. document disclaimer ?2011 zilog, inc. all rights reserved. in formation in this publication concerning the devices, applications, or technology described is intended to suggest possible uses and may be superseded. zilog, inc. do es not assume liability for or provide a representation of accuracy of the information, devices, or technology described in this document. zilog also does not assume liability for intellectual property infringement related in any manner to use of information, devices, or technology describe d herein or otherwise. the information cont ained within this document has been verified according to the general principles of electrical and mechanical engineering. zaura is a trademark of zilog, inc. all ot her product or service names are the property of their respective owners. warning:
zaura rf wireless library programmer?s reference manual RM006003-1011 revision history iii revision history each instance in this document?s revision history reflects a change from its previous version. for more deta ils, refer to the corresponding pages linked in the table below. date revision level description page no. oct 2011 03 corrected zaura_rf_ userparams value in additional radio configuration variables table. 20 oct 2011 02 updated library/apis to accommodate expanding radio frequencies. all feb 2011 01 original issue. all
zaura rf wireless library programmer?s reference manual revision history RM006003-1011 iv
zaura rf wireless library programmer?s reference manual RM006003-1011 table of contents v table of contents revision history. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii list of figures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix list of tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi the zaura rf wireless library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 zaura rf wireless module topology . . . . . . . . . . . . . . . . . . . . . . . . . .1 node addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2 radio frequencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 zaura rf wireless cell network identifiers . . . . . . . . . . . . . . . . . . . . .4 zaura rf wireless framing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 data transfer methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 frame formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6 reliable data transfer & flow control protocol . . . . . . . . . . . . . . .11 service access points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11 channel access rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12 radio states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14 zaura rf wireless module configuration . . . . . . . . . . . . . . . . . . . . . .15 radio configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15 other radio configuration options . . . . . . . . . . . . . . . . . . . . . . . . . .17 zaura rf shell configuration options . . . . . . . . . . . . . . . . . . . . .21 zaura rf wireless api reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23 zaura_rf_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23 zaura_rf_gpioconfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25 zaura_rf_getstate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27 zaura_rf_setstate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28 zaura_rf_transmit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30 zaura_rf_senddata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33 zaura_rf_sendseqdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34 zaura_rf_sendpkt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36 zaura_rf_receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38
zaura rf wireless library programmer?s reference manual table of contents RM006003-1011 vi zaura_rf_freebuf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 zaura_rf_readrssi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 zaura_rf_rssi2pwr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 zaura rf wireless radio configuration api. . . . . . . . . . . . . . . . . . . . . . . 43 zaura_rf_getparams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 zaura_rf_setparams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 zaura_rf_getaddr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 zaura_rf_setaddr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 zaura_rf_getnid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 zaura_rf_setnid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 zaura_rf_getrxfilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 zaura_rf_setrxfilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 zaura_rf_getchannel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 zaura_rf_setchannel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 zaura_rf_gettxpwr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 zaura_rf_settxpwr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 variable types and structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 zaura_rf_pkt_buf structure . . . . . . . . . . . . . . . . . . . . . . . . . . 58 zaura_rf_nid structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 zaura_rf_params structure . . . . . . . . . . . . . . . . . . . . . . . . . . 59 zaura_rf_stats structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 zaura rf wireless shell api reference . . . . . . . . . . . . . . . . . . . . . . . . . . 61 configuring zaura rf shell commands . . . . . . . . . . . . . . . . . . . . . . 61 creating user-defined zaura rf shell commands . . . . . . . . . . . . . . 62 console global variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 zaura rf wireless shell api descriptions . . . . . . . . . . . . . . . . . . . . . 64 zaura_rf_processcommandline() . . . . . . . . . . . . . . . . . . . . . . . . . . 65 zaura_rf_shelladdcmd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 zaura_rf_shellatox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
zaura rf wireless library programmer?s reference manual RM006003-1011 table of contents vii zaura_rf_shellstricmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70 zaura_rf_shellhexdump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71 zaura_rf_shellcontrol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72 zaura_rf_shellprintf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73 timer api functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77 zaura_rf_tickdelay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77 zaura_rf_ms_to_ticks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78 zaura_rf_readtimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79 zaura_rf_getticks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80 appendix a. project information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81 memory map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81 z8f2480 mcu peripherals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81 using zds ii to create an application . . . . . . . . . . . . . . . . . . . . . . . . . . .83 create an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84 customer support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
zaura rf wireless library programmer?s reference manual table of contents RM006003-1011 vii
zaura rf wireless library programmer?s reference manual RM006003-1011 list of figures ix list of figures figure 1. fields within the da frame . . . . . . . . . . . . . . . . . . . . . . . . .7 figure 2. fields within the da_sa frame . . . . . . . . . . . . . . . . . . . . . .9 figure 3. fields within the da_sa_ctrl frame . . . . . . . . . . . . . .10
zaura rf wireless library programmer?s reference manual list of figures RM006003-1011 x
zaura rf wireless library programmer?s reference manual RM006003-1011 list of tables xi list of tables table 1. center frequencies in the 86 3?870 mhz band . . . . . . . . . . .3 table 2. center frequencies in the 90 2?928 mhz band . . . . . . . . . . .3 table 3. service access point labels and functions . . . . . . . . . . . .11 table 4. zaura_rf_params structure settings . . . . . . . . . . . .15 table 5. additional radio configuration variables . . . . . . . . . . . . .17 table 6. uart configuration variables . . . . . . . . . . . . . . . . . . . . .21 table 7. z8f2480 mcu configuration variables . . . . . . . . . . . . . .22 table 8. types of variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57 table 9. zaura_rf_pkt_buf structure types . . . . . . . . . . . . .58 table 10. zaura_rf_nid structure types . . . . . . . . . . . . . . . . . .58 table 11. zaura_rf_params structure type . . . . . . . . . . . . . . .59 table 12. zaura_rf_stats structure type s . . . . . . . . . . . . . . . .59 table 13. console global variables . . . . . . . . . . . . . . . . . . . . . . . . . .63 table 14. library shell commands . . . . . . . . . . . . . . . . . . . . . . . . . .66 table 15. z8f2480 mcu gpios . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
zaura rf wireless library programmer?s reference manual list of tables RM006003-1011 xii
zaura rf wireless library programmer?s reference manual RM006003-1011 the zaura rf wireless library 1 the zaura rf wireless library this zaura rf wireless library programmer?s reference manual describes the architecture and applic ation programming interface that allows software developers to in tegrate zaura rf wireless modules into their products. zilog?s zaura rf wireless modules can be designed into any system to enable wireless control. the zaura rf wireless library is used to establish an ad-hoc peer-to-peer ne twork over radio frequencies in the industrial, scientific and medical (is m) band with raw data rates of 50 kbits/sec. nodes with compatible c onfigurations within radio range of each other can communicate directly using either point-to-point or point- to-multipoint data transfers. the z aura rf library allows developers to configure, transmit and recei ve packets on the networks. zaura rf wireless module topology the zaura rf wireless module uses an ad-hoc topology. nodes with compatible configurations within ra dio range of each other communicate directly using either po int-to-point (unicast) or point-to-multipoint (broadcast) data transfer. there is no central coordinating unit in the zaura rf wireless network through which nodes must communicate. this network does not provide routing of any kind between nodes that are not within radio range of each other. there is no concept of master or slave in the zaura rf wireless network; all nodes operate as equal peers. the modules? configuration parameters determine whether nodes will be able communicate with one an other when they are within range. the zaura rf wireless network conf iguration parameters consist of the rf channel, network id and frame format. there are two versions of the zaura rf wireless module, one using the 868 mhz frequency band and the other using the 915 mhz frequency band. the zaura rf channel determines which subset of fre quencies within the band are used
zaura rf wireless library programmer?s reference manual the zaura rf wireless library RM006003-1011 2 for communications. the network id is user-configurable value 1-4 bytes long that logically subd ivides a channel into se parate groups or cells. zaura rf modules using the same ch annel but different network id's will not be able to communicate with each other. the zaura rf wireless network prov ides both unreliable and reliable data transfer services, depending on the value of the frame format con- figuration parameter. there are three di fferent frame format s. the first, a da format, is an unreliable data tran sfer service with crc checking and up to 58 bytes of application data sent per frame. the second frame for- mat, da_sa, is the same as the da fra me format except that it adds the source address to the headers. th e third frame format, da_sa_ctrl, provides a reliable data transfer serv ice. of the three frame formats, the da_sa_ctrl format incurs the most overhead and is designed for instances in which reliable data transf er is more important than through- put. node addresses each node within the zaura rf wireless network should have a unique 8-bit address that allows all ot her nodes to identify that node. this is a mandatory requirement if the zaura rf wireless network is con- figured to use a frame format that includes the source address field. how- ever, if all nodes are conf igured to use frames that only carry a destination address and all transmissions are broadc ast, then there is no requirement for unique node addresses. a node can be assigned an address in the range 0x01 to 0xfe (i.e., 254 unique node addresses). node address 0xff is used as the broadcast address; i.e., when a frame is transmitted to the 0xff address, it will be received by all nodes w ithin radio range of the transmitter. node address 0x00 is reserved; it must not be used as a node address and should not be transmitted in either the destination or source address fields of a packet.
zaura rf wireless library programmer?s reference manual RM006003-1011 radio frequencies 3 the manner in which addresses are assigned to nodes is up to the imple- menter. the zaura rf wireless library contains a user-configurable node address that is stored in flash. radio frequencies the zaura rf wireless module uses radio frequencies in the 863? 870 mhz or 902?928 mhz bands. there are separate zaura rf wire- less module libraries for each band. the 863?870 mhz band is divided into 4 channels with 600 khz channel spacing and with the center fre quencies indicated in table 1. the 902?928 mhz band is divided into 25 channels with 1 mhz channel spacing and with the following cent er frequencies indicated in table 2. table 1. center frequencies in the 863?870 mhz band channel center frequency (mhz) 0865.6 1866.2 2866.8 3867.4 table 2. center frequencies in the 902?928 mhz band channel center frequency (mhz) channel center frequency (mhz) 0 903 13 916 1 904 14 917 2 905 15 918 3 906 16 919 4 907 17 920
zaura rf wireless library programmer?s reference manual the zaura rf wireless library RM006003-1011 4 all data communication oc curs at 50 kbps with a frequency deviation (fdev) of 100 khz and a modulation index (mi) of 4, regardless of the frequency band used. the zaura rf wireless network do es not implement frequency hop- ping. after a node has been configured to operate on a particular channel, it will continue to use that channel until the node is c onfigured to use a different channel. zaura rf wireless cell network identifiers a zaura rf wireless cell is composed of up to 254 peer nodes. each zaura rf wireless cell operates independently of all other cells; each cell uses a unique network identifier (nid). the size of the nid is a user- configurable parameter that must be between 1 and 4 bytes in length. because it may at times be difficult fo r the radio hardware to distinguish between a valid network id and noise (or the absence of any fsk signal), network identifiers should not contai n long sequences of repeated binary digits. for example, the 16-bit network id 0x0001 is a poor choice; whereas 0xa5b9 provides much better immunity to noise. 5 908 18 921 6 909 19 922 7 910 20 923 8 911 21 924 9 912 22 925 10 913 23 926 11 914 24 927 12 915 table 2. center frequencies in the 902?928 mhz band (continued) channel center frequency (mhz) channel center frequency (mhz)
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura rf wireless framing 5 zaura rf wireless cells operating w ithin radio range of one another can cause interference. therefore, over lapping cells must have different nid values. if possible, overlapping ce lls should use different rf chan- nels. zaura rf wireless addresses are not globally unique and can be reused in adjacent cells. zaura rf wireless framing this section describes the format of frames the zaura rf wireless nodes use to communicate. in this document a frame is used to describe the collection of bits transmitted and received by the radio and a packet is used to describe the portion of the frame that resides in host memory. data transfer methods each zaura rf wireless module accommodates two methods of data transfer: reliable and unreliable . each is described in this section. unreliable data transfer the unreliable data transfer mechanism employed by the zaura rf wireless library allows for either br oadcast (point-to-multipoint) or uni- cast (point-to-point) communication. after an unreliable data frame has been successfully transmitted, the se nder does not receive any indication that the frame was received by the intend ed recipient(s). this type of data transfer is supported by all frame formats. reliable data transfer reliable data transfer is only possi ble when all nodes within the zaura rf wireless cell are configured to use the da_sa_ctrl frame format. in addition, reliable data transfer is only supported for point-to-point communication; i.e., if a broadcas t frame is transmitted using the da_sa_ctrl frame format, the data transfer will be unreliable.
zaura rf wireless library programmer?s reference manual the zaura rf wireless library RM006003-1011 6 this transfer mechanism requires th e recipient of an sdata frame to provide feedback if the frame is actually received. this feedback arrives in the form of an acknowledgemen t (ack) frame. reception of an ack informs the transmitter that the recipient received the sdata frame as well as whether the sdata frame was accepted or rejected (invalid sequence number or no buffer space); it can optionally request the trans- mitter to delay the transmission of the next directed frame (reliable or unreliable) targeting the requestor. if a transmitter does not receive an ac k within a certain period of time after transmitting an sdata frame, it will automatically retransmit the frame a user-configurable number of times before it aborts the transmis- sion. if an ack has not been received after exhausting all retransmission attempts, the tran smitting application should no t assume that the target failed to receive the sdata frame. in this instance, the user application must perform some form of polling to determine if the target actually received the frame. when a wireless node retransmits a frame , it is possible for the target to receive multiple copies of the same frame. therefore, zaura rf wire- less sdata frames carry a sequence numb er and a retransmission bit that recipients use to distinguish between new and duplicate frames. frame formats the zaura rf wireless network can be configured to use one of three different frame formats: da, da_ sa and da_sa_ctrl. these frame formats differ in the length of the header included in every frame. extra header bytes reduce the effective data rate of the rf ch annel but allow for more complex data transfer modes (e.g., reliable data transfer). a user- configurable frame format allows th e zaura rf wireless network to be deployed in a wide range of applica tions. for proper communications, all nodes within a zaura rf wireless cell must be configured to use the same frame format.
zaura rf wireless library programmer?s reference manual RM006003-1011 frame formats 7 da frame format the simplest of the zaura rf wireless frame formats is da. fields within the da frame are depicted in figure 1. fields shown in white are configured by the zaura rf wireless library and cannot be modified by the user. the preamble (pa) is a fixed pattern of repeating 1010 bits ( 0xaa ). the radio hardware uses the preamble for synchronizing the receiver?s clock to the transmitter?s clock. the zaura rf library is configured to transmit two preamble bytes, but the radio will typically emit an extra pa as it prepares for transmission. the crc is calculated over the len, da and data fields. the zaura rf wireless module configures the radio hardware to automatically generate the crc on transmission and validate the crc upon packet reception. the zaura module only processes frames with a valid crc; the radio hardware automatically reject s frames with an invalid crc. the zaura module configures the radio to only accept packets that match the user-configurable network id (nid). the nid can be between 1 and 4 bytes. the longer the nid, the less susceptible the receiver will be to noise at a cost of a lower effectiv e data rate. zilog recommends using a nid of at least 2 bytes; this nid should not contain long sequences of repeated binary 1 or 0 digits. the length field (len) contains the number of bytes in the data field. note that the len fields of the rf frames include the number of bytes between the len field and the crc. the zaura rf wireless library automatically adjusts the length fiel d of received and transmitted packets figure 1. fields within the da frame pa(2) len(1) da(1) data(58) crc(2) nid(1C4)
zaura rf wireless library programmer?s reference manual the zaura rf wireless library RM006003-1011 8 so that the application only has to process the length of the application data. the da field contains the 8-bit target address of this frame. addresses 0x01 to 0xfe identify unique nodes within the zaura rf wireless cell. address 0x00 is reserved and must not be used as a node address or sent in the da or sa address of any frame. address 0xff is used to broadcast data to all nodes within the same zaura rf wireless cell that are in radio range of the transmitter. the zaura rf wireless module will only receive a frame targeting the broadcast address or its unique 8-bit address. promiscuous packet reception is not supported. the data field contains up to 58 by tes of application data. the zaura rf wireless module does not examine or interpre t the data field during packet transmission or reception. limitations and utility of the da format. the da frame format includes the least amount of rf header bytes and will be able to achieve the highest effective data rate of any of the zaura rf wireless frame formats. this frame format is most useful in applications where data flow is either unidirectional or all broadcas t. in these applications, knowing the identity of the node that transm itted the frame is not required. this data transfer mode is also useful in customer applications that use a proprietary frame format and protocol. the application is free to define additional header bytes within the zaura rf data fields. reliable zaura rf data services can not be used with the da frame for- mat. successful transmission of a frame using the da frame format does not imply that the target actually r eceived the frame; it only implies that no errors were encountered during transmission. da_sa frame format the only difference between the da _sa frame format and the da format is the addition of a source address (sa), as shown in figure 2.
zaura rf wireless library programmer?s reference manual RM006003-1011 frame formats 9 the zaura rf wireless library adds the sa field to all transmitted frames and makes the sa available to the application on all received packets. limitations and utility of the da_sa format. the da_sa format allows the recipient of a frame to know the identity of the node that trans- mitted the frame. this frame format is useful in ap plications that require unreliable bidirectional communicatio ns or point-to-point communication between unique nodes. as with the da format, the da_sa form at also allows the use of broad- cast traffic (point-multipoint) and cannot be used with the zaura rf reliable data transfer protocol. da_sa_ctrl frame format the da_sa_ctrl frame format uses a 3-byte rf header consisting of the destination address (da), sour ce address (sa) and the control (ctrl) field. the da and sa fields are identical to the corresponding fields in the da_sa frame format, and the control fi eld is used to identify the type of frame being transmitted as well as the target service access point (sap). the zaura rf library uses the following frame types: data. used to transmit applic ation data on a best-effort basis (unreliable data transmission) figure 2. fields within the da_sa frame pa(2) len(1) sa(1) da(1) data(58) crc(2) nid(1C4)
zaura rf wireless library programmer?s reference manual the zaura rf wireless library RM006003-1011 10 sdata. used to transmit application data using the zaura rf reliable data transfer and flow control (rdtfc) protocol (reliable data trans- mission). ack. used by the rdtfc to acknowledge receipt of an sdata frame the sap field can be used to segregat e application data into different log- ical streams. see the service access points section on page 11 for more information. the da_sa_ctrl format is shown in figure 3. this da_sa_ctrl frame format must be used to enable zaura rf reliable data services. the zaura rf wireless library is configured to use this frame format by default. limitations and utility of the da_sa_ctrl format. the da_sa_ctrl format allows the transmitter to dete rmine if the intend ed recipient of a packet actually received the data that was sent. this frame format also allows a simple point-to-point flow control mechanism to be implemented through the use of ack frames. when this frame format is used, the effective application data rate will typically be lower than that of the ot her frame formats because of a longer header as well as software overhead incurred with the operation of the reliable data transfer protocol. this frame format is most useful in applications where it is more impor- tant to know whether a frame was su ccessfully received than to transmit data as fast as possible. figure 3. fields within the da_sa_ctrl frame pa(2) len(1) ctrl(1) sa(1) da(1) data(58) crc(2) nid(1C4)
zaura rf wireless library programmer?s reference manual RM006003-1011 reliable data transfer & flow control 11 reliable data transfer & flow control protocol when the zaura rf wireless library is configured to use the da_sa_ctrl frame format, the appli cation can choose to send unicast frames unreliably or reliably via the reliable data transfer & flow con- trol (rdtfc) protocol. broadcast frames cannot be transmitted using rdtfc and will be sent unreliably even if the application requests reli- able delivery. the wireless reliable data transfer protocol cannot guarantee that a trans- mitted packet will be received by the ta rget (e.g., the target is out of radio range). in some cases it is not even possible for the transmitter to deter- mine that a target successfully received a frame (e.g., ack lost). even with these limitations, the rdtfc protoc ol ensures that the receiver will not accept duplicate frames. if the rd tfc indicates that a reliable data transfer succeeded, it guarantees the target actually received the frame. service access points when the zaura rf library is configured to use the da_sa_ctrl frame format, the least signi ficant four bits of the control field of data and sdata frames identify the target service access point (sap). a ser- vice access point is a process that expects data in a certain format and performs a specific function on that da ta. of the 16 possible sap values, 4 are reserved for the use of the zaur a rf library and the remaining 12 can be arbitrarily defined by the user?s application. table 3. service access point labels and functions sap label function 0?11 sap_app_0 to sap_app_11 defined by the application. 12 sap_reserved_12 reserved. 13 sap_reserved_13 reserved.
zaura rf wireless library programmer?s reference manual the zaura rf wireless library RM006003-1011 12 the application can use the sap field as a simple means to segregate data streams without having to use any byte(s) from the payload. it is up to the application to implement sap hand ling for receiving and transmitting sap_app packets. the use of the sap field is optional; therefore, this field is safe to ignore for r eceiving and transmitting data. the zaura rf wireless library defines two sap values that applica- tions may target when sending data: sap_uart_0 and sap_cmd_intrptr. data sent to sap_uart_0 will be bridged to uart_0 on the target device(s). the da ta field received is not interpreted by the receiving zaura rf wireless module prior to transmission on uart_0. data sent to the sap_cmd_intrptr mu st be ascii text that contains a valid console command. the string is not required to be null termi- nated. upon receipt of the ascii string, the remote zaura rf wireless module will process the comm and and send any output to zaura_rf_remoteconsolesap (a user-configurable parameter default- ing to sap_uart_0) of the node that issued the remote console com- mand. channel access rules the zaura rf wireless library can optionally be configured to per- form a carrier sense prior to transmitting a data or sdata frame to help prevent (but not eliminat e) the possibility that one node initiates a trans- mit operation while another node is al ready transmitting. if more than one 14 sap_uart_0 uart_0 output. 15 sap_cmd_intrptr comma nd interpreter input. table 3. service access point labels and functions (continued) sap label function
zaura rf wireless library programmer?s reference manual RM006003-1011 channel access rules 13 node is transmitting at an y given moment, it is unlik ely that a receiver in range of the transmitters will be ab le to successfully receive any frames. to perform a carrier sense before transmission, the zaura_rf_csattempts configuration variable mu st be set to a nonzero value. in this instance, the radio is placed into receive mode long enough to capture the current receive signal strength indicator (rssi). the higher the rssi value, the more rf energy the radio is detecting, and the more likely another station is already transmitting. if zaura_rf_csattempts is set to zero, rssi is not sampled prior to transmission (i.e., no carrier sense is performed). if the sampled rssi is below zaura_rf_rssithresh , the node will initi- ate transmission of the data or sdata frame. if the rssi value is greater than or equal to zaura_rf_rssithresh , the transmitting station deter- mines that the channel is in use. in this instance, the node will increment a chbusy counter (initialized to 0 each time the zaura_rf_transmit api is called) and will wait for a pseudo -random back-off period. after this pseudorandom delay, the node will again sample rssi if chbusy is less than zara_rf_csattempts . this process continues until the frame is transmitted (rssi < zaura_rf_rssithresh ) or the transmission is aborted ( chbusy reaches the value of zara_rf_csattempts ) and a sta- tus of zaura_rf_tx_channel_busy is returned to the caller. the back-off period is chosen at random on an interval of 164 to 419 ticks of the external 32.768 khz oscillator corresponding to a delay of approxi- mately 5.0 ms to 12.8 ms. prior to sending an ack frame, the z aura rf node will sample rssi if zaura_rf_csattempts is nonzero. however, unlike sending a data or sdata frame, there is no random back-off, and a chbusy counter is not used. instead, the node attemptin g to send an ack will initiate trans- mission as soon as rssi < zaura_rf_rssithresh . if the channel remains busy for a period of approxim ately 8 ms, then the node will abort transmission of the ack. if zaura_rf_csattempts is zero, then the
zaura rf wireless library programmer?s reference manual the zaura rf wireless library RM006003-1011 14 ack will be transmitted without performing a carrier sense to determine if the channel is busy. radio states the zaura rf module?s radio features five different operating states: sleep, standby, frequency synthesis, receive and transmit. because the zaura rf wireless network is half duplex, it is only possible to send data while the radio is in the transmit state, and it is only possible to receive data while the radio is in th e receive state. transmit and receive states are the two active modes of operation for the radio. the remaining states are power-saving modes that ca n be used to reduce the current con- sumption of the radio when it is not required for active operation. the radio consumes the leas t amount of current in the sleep state (approx- imately 80 a) and the most amount of current in the transmit state (up to 35 ma). the zaura rf library includes api functions to query and set the state of the radio. the library automatically transitions the radio to the transmit state from whatever st ate it is currently in when the zaura_rf_transmit api is called. the amount of time it takes to initiate a transmit opera tion depends on the current state of the radio. if the radio is in a very low power mode (sleep state), it will take the zaura rf libr ary longer to initiate the transmit operation than if the radio is in a medium power state (frequency synthe- sis or receive). similarly, it will take longer to transition the radio to the receive state from the sleep state than it will from standby state. when the zaura rf wireless library completes a transmit operation it automatically transitions the radio to a state corresponding to the value of the zaura_rf_idlestate configuration variable. by default, this vari- able is set to zaura_rf_receive. however, the application can mod- ify the value of the zaura_rf_idlesta te configuration variable to use a different state such as zaura_rf_sleep or zaura_rf_standby to reduce the radio?s current consumption.
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura rf wireless module configuration 15 zilog does not recommend set ting zaura_rf_idlestate to zaura_rf_transmit. if the ra dio should remain in the zaura_rf_transmit state, it will emit a continuous stream of extra preambles until the radio is placed in another state. while the radio is transmitting preambles, other zaura rf wireless nodes within range will sense a busy channel and will not be able to transmit. zaura rf wireless module configuration configuration of the zaura rf wire less library is determined by the value of a set of global variables contained in the zaura_rf_conf.c file, which must be linked to ever y zaura rf project. customers can optionally modify the values assigned to these configuration variables to modify the default behavior of the zaura rf library. radio configuration zaura_rf_params contains the zaura_rf_params structure and settings shown in table 4. table 4. zaura_rf_params structure settings structure member default range meaning reference network id contains the network identifier. all nodes that will communicate together must have the same network id. see zaura rf wireless cell network identifiers . nid.len (length of the id) 0x02 1?4 nid.value.data8[] 0x11,0x22,0x00, ? 0x00 4 bytes addr 0x1b 0x01?0xfe the address of this node. see node addresses . caution:
zaura rf wireless library programmer?s reference manual the zaura rf wireless library RM006003-1011 16 ch 0x01 868 mhz band (0?3) 915 mhz band (0?24) the channel to use within the rf frequency spectrum: ? the 868 mhz band has 4 channels ? the 915 mhz band has 25 channels see radio frequencies . tx pwr 0x00 0?7 set the transmit power (+13 dbm to ?8 dbm in increments of ?3 dbm). rxfilter 0x03 0x01, 0x03 specifies whether the broadcast packet should be passed to the application, such that: ? if 0x01, only accept packets directed to this node?s 8-bit address. ? if 0x03, accept packets directed to this node?s 8-bit address or to the broadcast address. table 4. zaura_rf_params structure settings (continued) structure member default range meaning reference
zaura rf wireless library programmer?s reference manual RM006003-1011 other radio configuration options 17 other radio configuration options additional rf configuration variab les and their default addresses are described in table 5. table 5. additional radio configuration variables variable default range description reference zaura_rf_ ? dest rf_bc_addr 0x01 to 0xff when issuing remote console commands or in data mode, the zaura_rf_dest address specifies the target address of the command/data. this value is placed in the da field of the corresponding data or sdata frame. n/a zaura_rf_ ? format xfer_da_sa_ ? ctrl xfer_da, xfer_da_sa, or xfer_da_sa_ ctrl defines the frame format used to communicate with zaura rf peers. all nodes within the same cell must be configured to use the same frame format. see zaura rf wireless framing . zaura_rf_ ? rssithresh 0x60 0x00 to 0xff when zaura_rf_csattempts is nonzero, zaura_rf_rssithresh determines the lowest rssi value that will cause the transmitter to defer transmitting for a random period of time between approximately 5.0 ms and 12.8 ms. see channel access rules .
zaura rf wireless library programmer?s reference manual the zaura rf wireless library RM006003-1011 18 zaura_rf_ ? csattempts 3 0x00 to 0xff determines if the zaura rf node listens for an idle channel before transmitting (carrier sense). if the channel is busy (rssi >= zaura_rf_rssithresh), the transmitter will wait a random back-off period (between 0 and approximately 5.0 ms and 12.8 ms) and repeat the cs until succeeding or reaching zaura_rf_csattempts. if zaura_rf_csattempts is 0, the node transmits without listening for an idle channel. see channel access rules . rfidlestate rf_receive rf_sleep, rf_standby or rf_receive determines the radio state to use after completing a transmit operation. not recommended to use a value of zaura_rf_transmit as the zaura_rf_idlestate. see zaura rf wireless shell api reference . table 5. additional radio conf iguration variables (continued) variable default range description reference
zaura rf wireless library programmer?s reference manual RM006003-1011 other radio configuration options 19 zaura_rf_ ? txdelay zaura_rf_ms _to_ticks(0) 0x0000 to 0xffff use a non-zero value to force a transmitter to delay its next transmission by the specified number of 32.768khz timer ticks. the zaura_rf_ms_to_tic ks macro can be used to convert an integer number of milliseconds into the corresponding number of timer ticks. see zaura rf wireless shell api reference . zaura_rf_ ? maxretry 3 0x00 to 0xff when sending sdata frames the transmitter expects to receive an ack frame from the target. if an ack is not received within approximately 10ms the transmitter will resend the packet up to zaura_rf_maxretry times before aborting transmission of the sdata frame. see reliable data transfer . table 5. additional radio conf iguration variables (continued) variable default range description reference
zaura rf wireless library programmer?s reference manual the zaura rf wireless library RM006003-1011 20 zaura_rf_ ? pauseunits 4 0 to 16 upon receipt of an sdata frame, the recipient sends an ack frame. if the receiver has fewer than 4 receive buffers remaining the ack can optionally request the transmitter to delay its next data frame directed to the sender of the ack between 0 and 16 pause delay units. each pause delay unit corresponds to approximately 25 ms. see reliable data transfer . zaura_rf_ ? userparams the zaura_rf_userparams buffer is an arbitrary block of 128 bytes used to store application level information to nonvolatile storage. the zaura_rf_demo program uses this variable to store the default wake-up message. table 5. additional radio conf iguration variables (continued) variable default range description reference
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura rf shell configuration options 21 zaura rf shell conf iguration options the five uart configuration variables are described in table 6. table 7 lists two configuration op tions specific to the z8f2480 mcu. table 6. uart configuration variables variable default range meaning zaura_rf_ ? dataescchar + any 8-bit value while in data mode, any character received on uart0 is transmitted to sap_app_0 of zaur a_rf_dest. uart0 returns to command mode after two consecutive zaura_rf_dataescchar bytes have been received. zaura_rf_ ? uartecho false true, false if true any character received on uart 0 is transmitted (echoed) on uart 0. uart echoing is typically enabled to allow visual confirmation of characters typed into a terminal emulator if the emulator is not configured for local echo. zaura_rf_ ? useuartfc true true, false when set to true data transfer over uart0 implements rts/cts flow control. zaura_rf_remote consolesap sap_uart_0 sap_app_0 to sap_app_11 or sap_uart_0 identifies the sap to which remote console output will be sent. zaura_rf_ ? uartbauddiv[4] {12, 6, 3, 3} an array of 4 x 16-bit values the zaura rf wireless library operates at 4 pre-defined frequencies of the f2480 ipo (11.06 mhz, 5.53 mhz, 2.76 mhz and 1.38 mhz). this table defines the uart baud rate divisor to use for each of the ipo settings.
zaura rf wireless library programmer?s reference manual the zaura rf wireless library RM006003-1011 22 table 7. z8f2480 mcu configuration variables variable default range meaning zaura_rf_ ? oscctrl1 0x82 0x80 = 11.06 mhz 0x81 = 5.53 mhz 0x82 = 2.76 mhz 0x83 = 1.38 mhz this variable is used to determine system clock frequency (via ipo). zaura_rf_ ? enablewdt true true, false determines whether the zaura rf wireless library enables the z8f2480 watchdog timer (wdt). if this variable is set to true, then after system initialization, the z8f2480 wdt will be enabled with a default time out of approximately 4.5 seconds. in this instance, it is necessary for the application to periodically issue the ez8 cpu?s "wdt" instruction to prevent a system reset due to a wdt time out.
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura rf wireless api reference 23 zaura rf wireless api reference this section describes the zaura rf wireless library apis. zaura_rf_init description the zaura_rf_init api is used to initialize the zara rf wireless library and prepare the radio for use. if the shell library (zaura_rf_shell.lib) is linked to the project it will also be initial- ized by the call to zaura_rf_init. this function must be called before any other zaura rf library or shell library api function is called. the first time an application calls this function zaura_rf_success is returned. subsequent calls will return zaura_rf_failure and will not re-initialize the library. during the initialization process the zaura rf library configures the z8f2480 gpio pins, initializes the module?s network and user parameters and configures the initial state of the radio. the zaura rf module is intended to be integrated with customer defined hardware platforms that may require some of the z8f2480 gpio pins to be configured in an application-specific manner. there- fore the zaura rf library calls the user-defined zaura_rf_gpioconfig api to establish a platform-specific gpio configuration. after calling zaura_rf_gpioconfig the library configures the set of gpio pins required for exclusive use of the mod- ule and (if appropriate) the zaura rf shell. the module.s network configuration is determined by the values assigned to the zaura_rf_params structure or values stored in flash (see zaura_rf_setparams). to determine which set of parameters are used the zaura rf library first checks if the param- eters stored in flash are valid (see zaura rf configuration). if they are valid, then the library will modify the zaura_rf_params struc- ture to use the values from flash. if the values in flash are invalid, the zaura rf library will use the values in the zaura_rf_params structure at the time the zaura_rf_init api was called (defaults specified in the zaura_rf_conf.c file). after the module?s network parameters have been configured, the zaura_rf_init api will initialize the value of the zaura_rf_userparams structure with values read from flash (always assumed to be valid). applications may modify the
zaura rf wireless library programmer?s reference manual zaura rf wireless api reference RM006003-1011 24 zaura_rf_userparams at run time as appropriate and should call zaura_rf_setparams before the system is turned off to ensure the modified parameters are written back to flash and available for use on subsequent power on reset events. upon return from this function the radio will be placed into the zaura_rf_idlestate which defaults to zaura_rf_receive. syntax zaura_rf_status zaura_rf_init( void ); parameters none. returns zaura_rf_success, zaura_rf_failure example /* initialize zaura rf wireless library */ zaura_rf_status status; status = zaura_rf_init();
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura_rf_gpioconfig 25 zaura_rf_gpioconfig description the zaura rf wireless library calls this user-defined function dur- ing system initialization to configure the z8f2480 mcu?s gpio port pins (as appropriate) for the particular hardware platform being used. because the zaura rf wireless module is a self-contained unit, the z8f2480 mcu?s pins, as used by the module, must never be used or reconfigured by the application. refer to the the z8f2480 mcu peripherals section on page 81 to determine which gpio port pins are available to the application. the default implementation of the zaura_rf_gpioconfig routine is contained in the gpioconfig.c file, which is located in the .\conf directory of the installation folder. syntax void zaura_rf_gpioconfig ( void ); parameters none. returns none. see also zaura_rf_init example void zaura_rf_gpioconfig ( void ) { /* * the shell library will reconfigure uart 0 rxd and txd * during initialization. if the shell library is not * used, pa4 and pa5 may be used by the application. */ paout = bit5; padd = bit4; pbout = 0; pbdd = 0;
zaura rf wireless library programmer?s reference manual zaura rf wireless api reference RM006003-1011 26 /* * the zaura rf library will configures these pins */ //pcout = 0; //pcdd = 0; pdaf = 0; pdout = 0; pddd = 0; /* * shell library reconfigures uart0 rts and cts pins * during initialization. if the shell library is not used * pe3 and pe4 may be used by the application. */ peout = 0; pedd = bit3; }
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura_rf_getstate 27 zaura_rf_getstate description this function retrieves the current radio state. syntax zaura_rf_state zaura_rf_getstate( void ); parameters none. returns current rf state. see also zaura_rf_setstate example zaura_rf_state state; state = zaura_rf_getstate();
zaura rf wireless library programmer?s reference manual zaura rf wireless api reference RM006003-1011 28 zaura_rf_setstate description when the application is not required to transfer data for extended peri- ods of time, the radio should be placed into zaura_rf_sleep state to reduce current consumption. however, it can take over 6 ms to wake up the radio from sleep state. if the radio will only be idle for shorter periods of time, use the zaura_rf_standby state. it will typi- cally take less than 2 ms to initiate a transmission or receive operation from standby state. because the zaura rf network is half duplex, it is only possible to receive data while the radio is in the zaura_rf_receive state. this state can be entered via an explicit call to this function or by con- figuring zaura_rf_idlestate to zaura_rf_receive. when zaura_rf_idlestate is set to zaura_rf_receive, the zaura rf wireless library will automatically configure the radio for recep- tion after each transmit operation completes. under normal circumstances, the application should never have to explicitly set the radio to the zaura_rf_freq_synth or zaura_rf_transmit states. the zaura rf library will auto- matically step the radio through these states during the process of data transfer. furthermore, if the radio is allowed to remain in the zaura_rf_transmit state after completing the transmission of a data frame, it will emit a continuous stream of extra preambles until the radio is placed into another state. while the radio is transmitting pre- ambles, other zaura rf nodes within range will sense a busy chan- nel and will not be able to transmit. therefore, zilog recommends never setting zaura_rf_idlestate to zaura_rf_transmit. this function returns zaura_rf_success when called with a valid state parameter; otherwise, zaura_rf_invalid_param is returned. syntax zaura_rf_status zaura_rf_setstate( zaura_rf_state state ); parameters state: specifies new radio state. permissible states are: ? ? zaura_rf_sleep ? zaura_rf_standby ? zaura_rf_freq_synth ? zaura_rf_receive ? zaura_rf_transmit
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura_rf_setstate 29 returns zaura_rf_success ? zaura_rf_invalid_param see also zaura_rf_getstate example zaura_rf_status status; status = zaura_rf_setstate( zaura_rf standby );
zaura rf wireless library programmer?s reference manual zaura rf wireless api reference RM006003-1011 30 zaura_rf_transmit description the zaura_rf_transmit api sends data to a specific node ( 0x00 < dest < 0xff ) or broadcasts the data to all nodes within range of the transmitter (dest = zaura_rf_bc_addr). the data will be transferred reliably or unreliably, depending on the values of the dest and ctrl parame ters. data transfer will be reli- able using the rdtfc if the ctrl parameter specifies the use of an sdata frame; the dest parameter is not zaura_rf_bc_addr ( 0xff ) and the zaura_rf_format configuration variable is set to xfer_da_sa_ctrl. if any of these conditions is not satisfied, the data will be transferred unreli- ably. the ctrl field is meani ngless if the zaura_rf_format configuration variable is set to either xfer_da or xfer_da_sa. a return code of zaura_rf_success means different things depending on whether rdtfc was used or whether the data was sent unreliably with a data frame. if the data was transported via a data frame, then zaura_rf_success indicates that the transmitter did not encounter any errors while sending the frame. if the data was sent using an sdta frame, zaura_rf_success indicates that the peer node acknowledged and accepted the frame. a return code of tx_channel_busy indicates that the data was not transmitted because the channel was in use. this status can only be returned if the zaura_rf_csattempts configuration variable is non- zero, because a zero value disables carrier sensing before transmission. a zaura_rf_tx_not_ack status means that the sdata frame was successfully transmitted but no acknowledgement was received after zaura_rf_maxretry +1 attempts to transmit the sdata frame. as a result, either the target did not receive the sdata frame or the transmitter did not receive the ack. a zaura_rf_tx_nak status indicates that the sdata frame was successfully transmitted and an ack was received. however, the ack indicates that the target rejected the data due to a sequence error. this situation can occur if the first transmission of the sdata frame is received and accepted by the target but the target?s ack is lost. in this instance, the transmitter will attempt to retransmit the sdata frame and the target will reject the data as a duplicate. the zaura_rf_tx_nak status could also indicate that the recipient was unable to accept the otherwise-valid sdta frame because no buf- fer space was available to hold the data.
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura_rf_transmit 31 all sdata transmit requests are synchronous, meaning control is not returned to the calling application until the frame has been transmitted and an ack has been received, or until all retransmission attempts have failed. all data transmit requests are asynchronous, meaning the zaura_rf_transmit api will return control to the caller possibly before the frame has been completely sent. therefore, the application should not explicitly change the radio state until the transmit operation completes (see zaura_rf_getstate on page 27). there is no need to wait for the previous data frame to complete transmission before calling the zaura_rf_transmit api again. the data to be transmitted is buffered by the zaura rf wireless library before it returns control from the z aura_rf_transmit api. therefore, the application may modify the data buffer prior to completion of the actual transmission. the zaura_rf.h header file also defines several macros that call the zaura_rf_transmit api. these macros include: syntax int8 zaura_rf_transmit( zaura_rf_addr dest, uint8 ctrl, handle hdata, uint8 len ); parameters zaura_rf_senddata used to send data packets to sap_app_0. zaura_rf_sendseqdata used to send sdata packets to sap_app_0. zaura_rf_sendpkt uses a packet buffer structure to call zaura_rf_transmit. dest specifies the node(s) target ed by the transmit operation. ctrl specifies frame type (data or sdata) and target sap. note:
zaura rf wireless library programmer?s reference manual zaura rf wireless api reference RM006003-1011 32 returns zaura_rf_success zaura_rf_invalid_param zaura_rf_tx_not_ack (only applicable to sdata frames) zaura_rf_tx_nak (only applicable to sdata frames) zaura_rf_tx_channel_busy see also zaura_rf_senddata , zaura_rf_sendseqdata , zaura_rf_sendpkt , zaura_rf_receive , zaura_rf_pkt_buf structure example zaura_rf_status status; // send a broadcast (unreliable data transfer) to sap_app_0 on all remote nodes status = zaura_rf_transmit( zaura_rf_bc_addr, data | sap_app_0, "hello" , 5 ); // send a message to sap_app_5 on node 0x23 using the zaura rdtfc protocol status = zaura_rf_transmit( 0x23, sdata | sap_app_5, "hello" , 5 ); hdata arbitrary pointer to th e data to be transmitted. len the number of bytes of data referenced by hdata ? (<= zaura_rf_max_data_len).
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura_rf_senddata 33 zaura_rf_senddata description the zaura_rf_senddata macro sends data (using unreliable data transfer) to sap_app_0 on remote node(s). syntax zaura_rf_status zaura_rf_senddata(zaura_zaura_rf_addr dest, han- dle hdata, uint8 len) parameters returns zaura_rf_success is returned if the transmissions did not encounter any errors. this only means it was transmitted, not that it was received. ? ? tx_channel_busy is returned if the channel was in use. (see channel access rules for more information). see also zaura_rf_transmit , zaura_rf_sendseqdata , zaura_rf_sendpkt , zaura_rf_receive , zaura_rf_pkt_buf structure example 1 zaura_rf_senddata( zaura_rf_bc_addr, "hello world", 11 ); example 2 uint16 data = 0x1234; zaura_rf_senddata( zaura_rf_dest, &data, 2 ); dest zaura_zaura_rf_addr value for th e destination address. addresses 0x01 through 0xfe are specific nodes (point-point), 0xff is a broadcast address (point-multipoint). hdata an arbitrary pointer to the application data. len the number of bytes referenced by hdata.
zaura rf wireless library programmer?s reference manual zaura rf wireless api reference RM006003-1011 34 zaura_rf_sendseqdata description the zaura_rf_sendseqdata macro sends data (using rdtfc) to sap_app_0 on a remote node. syntax zaura_rf_status zaura_rf_sendseqdata( zaura_rf_addr dest, handle hdata, uint8 len) parameters returns zaura_rf_success is returned if the peer node acknowledged and accepted the frame. tx_channel_busy is returned if th e channel was in use (see chan- nel access rules for more information). zaura_rf_tx_not_ack is returned if no acknowledgement was received. this return result could either be that the packet did not arrive at its destination or the ack was not received. rf_tx_nak is returned if the node re ceived the frame but rejected the frame because no buffer space was available to hold the data. see also zaura_rf_transmit , zaura_rf_senddata , zaura_rf_sendpkt , zaura_rf_receive , zaura_rf_pkt_buf structure example /* send reliable data to node */ zaura_rf_sendseqdata( 0x23, "hello world", 11 ); dest zaura_rf_addr value for the destination address. addresses 0x01 through 0xfe are specific node s (point-to-point). hdata a void pointer to the application byte data. len uint8 value spec ifies the length of the valid bytes referenced by hdata.
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura_rf_sendpkt 35 zaura_rf_sendpkt description the rfsendpkt macro sends data to remote node(s) using a packet buf- fer structure. this packet buffer structure can be obtained from the zaura_rf_receive api or defined within application memory space. the calling application retains control of the packet buffer after this function returns. the data will be transferred reliably or unreliably, depending on the values of the dst and ctrl members of the packet buf- fer structure (see zaura_rf_transmit on page 30 for more infor- mation). syntax zaura_rf_status zaura_rf_sendpkt( zaura_rf_pkt_buf * pbuf) parameters returns the return value depends on the type of packet that was sent. for unreliable data transmissions (including broadcast): ? zaura_rf_success is returned if the transmissions did not encounter any errors. this only means it was transmitted, not that it was received ? tx_channel_busy is returned if the channel was in use. (see channel access rules for more information) ? for reliable sdata transmissions: ? zaura_rf_success is returned if the peer node acknowledged and accepted the frame ? tx_channel_busy is returned if the channel was in use (see channel access rules for more information) ? zaura_rf_tx_not_ack is returned if no acknowledgement was received. this could be either the packet did not arrive at desti- nation or the ack was note received ? rf_tx_nak is returned if the node received the frame but rejected the frame because no buffer space was available to hold the data pbuf a pointer to a packet buffer structur e that contains the information to be transmitted.
zaura rf wireless library programmer?s reference manual zaura rf wireless api reference RM006003-1011 36 see also zaura_rf_transmit , zaura_rf_sendseqdata , zaura_rf_senddata , zaura_rf_receive , zaura_rf_pkt_buf structure example ppkt = rfreceive(); if( ppkt != nullptr ) { /* * forward this packet to sap_app_1 on zaura_rf_dest using rdtfc */ ppkt->dst = zaura_rf_dest; ppkt->ctrl = sdata | sap_app_1; zaura_rf_sendpkt( ppkt ); zaura_rf_freebuf( pbuf ); }
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura_rf_receive 37 zaura_rf_receive description when the zaura rf module receives a frame, the zaura rf wireless library attempts to allocate a packet buffer structure to hold the packet. the allocated packet buffer is then added to a queue of received packets waiting for application processing. to retrieve the next packet from the queue, an application must call the zaura_rf_receive api. if the receive packet queue is empty, this function returns nullptr; otherwise it returns a pointer to a packet buffer structure containing the data to be processed. after the applica- tion has finished processing the received packet, it must call zaura_rf_freebuf to pass the packet buffer pointer obtained from this api as an argument. syntax zaura_rf_pkt_buf * zaura_rf_receive( void ) parameters this function does not contain any parameters. returns a pointer to a zaura_rf_pkt_buf structure. if there are no receive packets available, a null pointer will be returned. see also zaura_rf_freebuf , zaura_rf_pkt_buf structure example zaura_rf_pkt_buf * ppkt; ppkt= zaura_rf_receive(); if( ppkt ) { /* * process the packet here */ zaura_rf_freebuf(); }
zaura rf wireless library programmer?s reference manual zaura rf wireless api reference RM006003-1011 38 zaura_rf_freebuf description the zaura_rf_freebuf api is called to return control of a packet buffer to the zaura rf wireless library after the application has fin- ished processing the packet. an application acquires control of a packet buffer structure when the zaura_rf_receive api returns a nonzero value. if an application fails to call zaura_rf_freebuf after processing a received packet, the zaura rf library will even- tually run out of packet buffers, thereby preventing subsequent data transfers. syntax void zaura_rf_freebuf(zaura_rf_pkt_buf * ppkt) parameters returns none. see also zaura_rf_receive , zaura_rf_pkt_buf structure example see zaura_rf_receive example. ppkt a pointer to the packet buffer to be released back into the packet buffer pool.
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura_rf_readrssi 39 zaura_rf_readrssi description this function stores the current receive signal strength indicator (rssi) in the zaura_rf_rssi global variable and returns the value of the global variable to the caller. the rssi value returned is an 8-bit quantity that can range from 0x00 to 0xff . typically, the rssi value varies over a narrower range. rssi can only be sampled if the radio is in the zaura_rf_receive state. if the radio is not in the zaura_rf_receive state when this function is called, a value of 0xff is returned. the rssi can be used as a relative indicator of the amount of rf energy the receiver is detecting. a higher value indicates the presence of more energy (i.e., close to the transmitter) and a lower value indi- cates only the presence of noise (no signal being transmitted). the rssi value returned can be passed to the zaura_rf_rssi2pwr function to estimate the signal strength in dbm. because the zaura rf wireless library can optionally be config- ured to perform carrier sensing (via rssi sampling) prior to transmit- ting data frames, there is typically no need for the application to call this function before calling the zaura_rf_transmit routine. this function is most useful while scanning zaura rf channels to deter- mine which channels are in use. syntax uint8 zaura_rf_readrssi( void ); parameters none. returns the current rssi value. see also zaura_rf_rssi2pwr , zaura_rf_getstate , zaura_rf_setstate example uint8 currssi; note:
zaura rf wireless library programmer?s reference manual zaura rf wireless api reference RM006003-1011 40 currssi = zaura_rf_readrssi();
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura_rf_rssi2pwr 41 zaura_rf_rssi2pwr description this function returns a signed 8-bit value representing the (approxi- mate) power level (in dbm) of the rssi parameter. syntax int8 zaura_rf_rssi2pwr(uint8 rssivalue) parameters returns returns a signed 8-bit value representing the approximate power level in dbm of the received signal strength. see also zaura_rf_readrssi , zaura_rf_getstate , zaura_rf_setstate example int8 pwr; uint8 currssi; currssi = zaura_rf_readrssi(); pwr = zaura_rf_rssi2pwr( currssi ); rssivalue rssi 8-bit value, typically re turned from zaura_rf_readrssi() function.
zaura rf wireless library programmer?s reference manual zaura rf wireless api reference RM006003-1011 42
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura rf wireless radio configuration api 43 zaura rf wireless radio configuration api this section of the api allows develo pers to configure the radio parame- ters programmatically at run time to override the compile time configura- tion defined in the zaura_rf_conf.c file. changes made to the rf parameters at run time as a result of calling apis in this section are not saved to nonvolatile storage (flash ) unless the application calls the zaura_rf_setparams api (see the zaura rf wireless module con- figuration section on page 15).
zaura rf wireless library programmer?s reference manual zaura rf wireless radio co nfiguration api RM006003-1011 44 zaura_rf_getparams description this function reads the rf and user parameters stored in flash. if the flash-based rf parameters are valid, the ram-based zaura_rf_params configuration variable is updated with the values read from flash. if the flash-based rf parameters are invalid, the ram-based zaura_rf_params configuration variable is not modi- fied. prior to returning to the caller, this function will configure the rf module with values stored in the ram-based zaura_rf_params configuration variable. the user parameters read from flash are always assumed to be valid and will overwrite the contents of the ram-based zaura_rf_userparams configuration variable. the zaura rf wireless library calls this function during initializa- tion to determine whether the rf parameters from flash or the default values specified in the zaura rf configuration file will be used to initialize the radio. syntax void zaura_rf_getparams( void ); parameters none. returns none. see also zaura_rf_setparams , zaura_rf_params structure , zaura rf wireless module configuration example zaura_rf_getparams(); /* * if the rf parameters stored in flash were valid, the * zaura_rf_params global variable now contains the values * stored in flash and the radio has been reprogrammed to * use the rf parameters stored in flash. * * in addition the ram-based zaura_rf_usserparams global * variable will be overwritten with the values from * flash. **/
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura_rf_setparams 45 zaura_rf_setparams description this routine writes the contents of the zaura_rf_params and zaura_rf_userparams global variables to flash. the zaura rf wireless library also writes private configuration information to flash when this api is called. whenever any of the rf parameters is modified by a shell command, the zaura rf library calls this function to update the corresponding parameter in flash. if the application uses a library api function to modify the rf parameters, the application should call this routine to ensure that the modified parameter(s) are written to flash and will be used to configure the radio on the next power-on reset event. syntax void zaura_rf_setparams( void ); parameters none. returns none. see also zaura_rf_getparams , zaura_rf_params structure , zaura_rf_userparams description in table 5 . example /* * change this node's rf address to 0x23 and store the new * rf configuration in flash. */ zaura_rf_getparams(); zaura_rf_params.addr = 0x23; zaura_rf_setparams();
zaura rf wireless library programmer?s reference manual zaura rf wireless radio co nfiguration api RM006003-1011 46 zaura_rf_getaddr description this function returns the zaura rf node address currently pro- grammed into the radio. the default node address is specified in the addr member of the zaura_rf_params structure. the address can be modified using the zaura_rf_setaddr function or the addr shell command. syntax zaura_rf_addr zaura_rf_getaddr( void ); parameters none. returns the 8-bit node address. see also zaura_rf_setaddr , zaura_rf_getparams , zaura_rf_params structure example zaura_rf_addr addr; addr = zaura_rf_getaddr();
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura_rf_setaddr 47 zaura_rf_setaddr description this function is used to modify the zaura rf node address used by the radio. if the node address is in the range of 0x01 to 0xfe , the radio is reconfigured to use the new address, the zaura_rf_params structure is updated and zaura_rf_success is returned. other- wise, zaura_rf_invalid_param is returned and the node address is not modified. the zaura rf wireless library does not verify the uniqueness of the address. the application designer is responsible for assigning unique addresses to all nodes within the zaura rf cell. syntax zaura_rf_status zaura_rf_setaddr( zaura_rf_addr addr ); parameters addr: the 8-bit node address. returns zaura_rf_success ? zaura_rf_invalid_param see also zaura_rf_getaddr , zaura_rf_setparams , zaura_rf_params structure example zaura_rf_status status; status = zaura_rf_setaddr( 0x23 );
zaura rf wireless library programmer?s reference manual zaura rf wireless radio co nfiguration api RM006003-1011 48 zaura_rf_getnid description this function retrieves the zaura rf network id (nid) currently programmed into the radio. all nodes within the same zaura rf cell must use the same nid (and channel) to communicate with each another. the default nid is specified in the nid member of the zaura_rf_params structure. the nid can be modified using the zaura_rf_setnid function or the nid console command. syntax void zaura_rf_getnid( rf_nid * pnid ); parameters returns none. see also zaura_rf_setnid , zaura_rf_getparams , zaura_rf_nid structure , zaura_rf_params structure example zaura_rf_nid curnid; zaura_rf_getnid( &curnid ); pnid a pointer to a network id struct ure initialized with the current nid.
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura_rf_setnid 49 zaura_rf_setnid description this function is used to modify the zaura rf network id (nid) used by the radio. all nodes within the same zaura rf cell must use the same nid (and channel) to communication with one another. the nid is an arbitrary value between 1 and 4 bytes in length. if the nid is of the proper length, the radio is reconfigured to used the new nid, the zaura_rf_params structure is updated and zaura_rf_success is returned. otherwise, zaura_rf_invalid_param is returned and the current nid is not modified. to improve the radio?s immunity to noise, the caller should avoid using nid values that contain long sequences of repeated binary 1 or 0 dig- its. for example, the nid value 0x00000001 should be avoided because a single pulse of rf energy near the channel centre frequency could be misinterpreted as a valid nid. syntax zaura_rf_status zaura_rf_setnid( rf_nid * pnid ); parameters returns zaura_rf_success, zaura_rf_invalid_param see also zaura_rf_getnid , zaura_rf_setparams , zaura_rf_nid structure , zaura_rf_params structure example zaura_rf_nid mynid; zaura_rf_status; mynid.len = 2; mynid.value.data8[0] = 0x11; mynid.value.data8[1] = 0x22; status = zaura_rf_setnid( &mynid ); pnid points to a new nid.
zaura rf wireless library programmer?s reference manual zaura rf wireless radio co nfiguration api RM006003-1011 50 zaura_rf_getrxfilter description this function retrieves the receiver filter setting currently programmed into the radio. the receive filter is used to decide whether an inbound frame should be accepted or silently discarded at the hardware level. the default receive filter setting is specified in the rxfilter member of the zaura_rf_params structure. the filter setting can be modified using the zaura_rf_setrxfilter function or the filter shell command. see zaura_rf_setrxfilter on page 51 to review the definitions of the filter flags. syntax uint8 zaura_rf_getrxfilter( void ); parameters none. returns current filter setting (0 to 3) see also zaura_rf_setrxfilter , zaura_rf_getparams , zaura_rf_params structure example uint8 rxfilter; rxfilter = zaura_rf_getrxfilter();
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura_rf_setrxfilter 51 zaura_rf_setrxfilter description this function modifies the filter setting that the radio uses when decid- ing to accept inbound frames. only the bottom 2 bits of the filter argu- ment are processed to ensure that the new filter setting is always between 0 and 3. after calling this function, the new filter setting is programmed into the radio and the zaura_rf_params structure is updated with the new filter setting. when using the zaura rf rdtfc protocol, the filter parameter should be set to either 1 or 3. in particular, the use of promiscuous mode (filter = 0) is not supported because it will defeat the rdtfc protocol. nodes using a filter setting less than 3 will not be able to receive broadcasts. syntax void zaura_rf_setrxfilter( uint8 filter ); parameters filter. the filter settings are: 0 = any address (promiscuous). 1 = node address. 2 = node address + 0x00 reserved address. 3 = node address + 0x00 reserved address + 0xff broadcast address (zaura_rf_bc_addr). returns zaura_rf_success, zaura_rf_invalid_param see also zaura_rf_getrxfilter , zaura_rf_setparams , zaura_rf_params structure example zaura_rf_setfilter( 3 );
zaura rf wireless library programmer?s reference manual zaura rf wireless radio co nfiguration api RM006003-1011 52 zaura_rf_getchannel description returns the 0-based channel number that the radio is currently using for communication. the default rf channel is specified in the ch member of the zaura_rf_params structure. the rf channel can be modified using zaura_rf_setchannel function or the ch shell command. syntax uint8 zaura_rf_getchannel( void ); parameters none. returns current channel setting (0 to the maximum number of channels ? 1) see also zaura_rf_setchannel , zaura_rf_getparams , zaura_rf_params structure example uint8 curch; curch = zaura_rf_getchannel();
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura_rf_setchannel 53 zaura_rf_setchannel description the channel parameter must be between 0 and the maximum number of channels minus 1. the value of maxchannels depends on which version of the zaura rf wireless library is linked to the project. the zaura rf_866p5_mhz library uses 4 channels (i.e., the chan- nel parameter must be between 0 and 3). the zaura rf_915_mhz library uses 25 channels (i.e., the channel parameter must be between 0 and 24). for specific channel frequencies, see the radio frequencies section on page 3. if the channel parameter is valid, the radio configuration is modified, the new channel number is stored in the ch member of the zaura_rf_params structure and zaura_rf_success is returned. if the channel number is invalid, zaura_rf_invalid_param is returned and the current channel is not modified. syntax zaura_rf_status zaura_rf_setchannel( uint8 channel ); parameters channel: the new channel on which to communicate. returns zaura_rf_success, zaura_rf_invalid_param see also zaura_rf_getchannel , zaura_rf_setparams , zaura_rf_params structure example zaura_rf_status status; status = zaura_rf_setchannel( 1 );
zaura rf wireless library programmer?s reference manual zaura rf wireless radio co nfiguration api RM006003-1011 54 zaura_rf_gettxpwr description this function returns a 3-bit value indicating the current transmit power level setting of the radio. the default transmit power level is specified in the txpwr member of the zaura_rf_params structure. the transmit power level can be modified using zaura_rf_settxpwr function or the pwr shell command. syntax uint8 zaura_rf_gettxpwr( void ); parameters none. returns power level setting (between 0 and 7) used during transmission. see also zaura_rf_settxpwr , zaura_rf_getparams , zaura_rf_params structure example uint8 curpwr; curpwr = zaura_rf_gettxpwr();
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura_rf_settxpwr 55 zaura_rf_settxpwr description this function modifies the power level at which the radio transmits. if the pwr parameter is between 0 and 7, the radio configuration is modi- fied, the new power level is stored in the zaura_rf_params struc- ture and zaura_rf_success is returned. if the power level is invalid, zaura_rf_invalid_param is returned and the current radio configuration is not modified. syntax zaura_rf_status zaura_rf_settxpwr( uint8 pwr ); parameters pwr: specifies the new transmit power level setting. valid settings are: returns zaura_rf_success, zaura_rf_invalid_param see also zaura_rf_gettxpwr , zaura_rf_setparams , zaura_rf_params structure example zaura_rf_status status; status = zaura_rf_settxpwr( 0 ); 0+13 dbm 1+10 dbm 2 +7 dbm 3 +4 dbm 4 +1 dbm 5 ?2 dbm 6 ?5 dbm 7 ?8 dbm
zaura rf wireless library programmer?s reference manual zaura rf wireless radio co nfiguration api RM006003-1011 56
zaura rf wireless library programmer?s reference manual RM006003-1011 variable types and structures 57 variable types and structures this section describes the types of rf wireless library configuration variables featured in the zaura rf wireless modules, as well as their data containment structures. for mo re information ab out the variables themselves, see the zaura rf wireless module configuration section on page 15. types table 8 describes the types of vari ables employed by the zaura rf wireless configuration api. structures the zaura rf wireless library employs four types of data structures: zaura_rf_pkt_buf, zaura_rf_nid, zaura_rf_params and zaura_rf_stats. each of these structures is described in this section. table 8. types of variables name description uint8 unsigned 8-bit integer int8 signed 8-bit integer uint16 unsigned 16-bit integer uint32 unsigned 32-bit integer handle void pointer (void *) zaura_rf_addr uint8 zaura_rf_status signed 8-bit integer zaura_rf_state enumeration of state types
zaura rf wireless library programmer?s reference manual variable types and structures RM006003-1011 58 zaura_rf_pkt_buf structure the zaura_rf_pkt_buf structure is used to hold a packet for pro- cessing, receive or transmit. it contai ns the structure types indicated in table 9. zaura_rf_nid structure the zaura_rf_nid structure is used to hold the network id informa- tion. it contains the structure types indicated in table 10. in the following code snippet, the first column represents each union type; the second column represents its value. { uint8 data8[4] table 9. zaura_rf_pkt_buf structure types member type description len uint8 length of the application data packet. dst zaura_rf_ad dr destination. src zaura_rf_ad dr source (valid on da_sa, da_sa_ctrl frames). ctrl uint8 control byte (valid on da_sa_ctrl frames). data[] uint8 array of application-specific data bytes in the packet. table 10. zaura_rf_nid structure types member type description len uint8 the number of bytes that are valid in data. value union the network id byte(s).
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura_rf_params structure 59 uint16 data16[2] uint32 data32 } zaura_rf_params structure the zaura_rf_params structure is used to hold the configuration parameters for the radio. it contai ns the structure types indicated in table 11. zaura_rf_stats structure the zaura_rf_stats structure is used to hold the statistics for the radio. these stats can be accessed through the global variable zaura_rf_stats . the zaura_rf_stats structure contains the structure types indicated in table 12. table 11. zaura_rf_params structure type member type description nid zaura_rf_nid network id information. addr zaura_rf_ad dr local address of this node. ch uint8 current channel. txpwr uint8 transmit power level. rxfilter uint8 receive filter. table 12. zaura_rf_stats structure types member type description rxpkts; uint16 total number of packets received. rxbytes; uint32 total bytes received. rxnobuf; uint16 number of buffers.
zaura rf wireless library programmer?s reference manual variable types and structures RM006003-1011 60 rxack; uint16 total received acknowledgments. rxnak; uint16 total received negative acks. rxpause; uint16 total number of pauses requests received. rxretry; uint16 total number of retries received. txpkts; uint16 total packets transmitted. txbytes; uint16 total bytes transmitted. txur; uint16 transmit underruns issued. txbusy; uint16 number of failed transmit attempts due to a busy rf channel. txack; uint16 total acknowledgments issued. txnak; uint16 total negative acknowledgements issued. txretry; uint16 total number of retries issued. txpause; uint16 total number of pause requests issued. table 12. zaura_rf_stats st ructure types (continued) member type description
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura rf wireless shell api reference 61 zaura rf wireless shell api reference the zaura rf wireless library incl udes a configurable interactive command interpreter (shell), using uart 0 as the console. the shell library provides a base set of comman ds and allows you to add optional commands from the shell library or add user-defined shell commands. the shell also provides the ability to set up remote cons ole support (simi- lar to telnet), allowing you to control a remote zaura rf node. con- sole commands received by the local zaura rf shell are sent wirelessly to remote node(s) for processing. console output from the operation of the shell command on the remote node(s) is transmitted back to the originating zaura rf node and displayed on the local console. the shell is an optional component in zaura rf wireless projects. if your application requires the use of th e shell, the project must link to the zaura_rf_shell.lib library. if your project does not require the use of the shell, your application must not call any shell function. in this instance, your project must link to the no_shell.lib library. configuring zaura rf shell commands the zaura rf module shell user manual (um0235) describes the default set of shell commands and all predefined shell commands that can optionally be added to zaura rf applications. to add any nondefault command to the zaura rf shell, use the zaura_rf_shelladdcmd api to pass the ascii name assigned to the command as well as a func- tion pointer to the routine that implements the command. the zaura_rf_shelladdcmd api is used regardless of whether the com- mand being added to the shell is an optional zaura rf shell command or a user-defined shell command.
zaura rf wireless library programmer?s reference manual zaura rf wireless shell api reference RM006003-1011 62 creating user-defined zaura rf shell commands the zaura rf shell library provid es a set of utility functions and global variables that applications can use to build custom shell com- mands. to implement a user-defined shell command, it is necessary to understand how the zaura rf she ll library processes ascii text from the console. as a user enters characters on the console, the zaura rf shell library buffers these characters and increments a global counter to track the num- ber of characters entered (zaura_rf_uartavail). after the user presses the enter key, the shell library detect s a carriage return in the console input stream and sets the zaura_rf_u arteol flag to true to indicate that a command line has been received. applications that use the zaur a rf shell must monitor the zaura_rf_uarteol flag and call zaura_rf_shellprocesscmdline at noninterrupt time to allow the sh ell library to interpret the command just entered. after the zaura_rf_uarteol flag is set to true, the shell library stops buffering console input. ther efore, applications should call zaura_rf_shellprocesscmdline soon after this flag is set to avoid lost console input. alternatively, the cons ole program can be configured to insert delays between command lines. the zaura_rf_shellprocesscmdline function parses the console input into space-delimited tokens that are referenced by the pzaura_rf_tokens array. the first token (at index 0 in pzaura_rf_tokens array) is always the name of the console com- mand, and the remaining tokens (if an y) point to user-supplied parame- ters. example. if the user enters test 1 2 3 on the console, the zaura rf shell will recognize 4 tokens. the first token contains the value test and note:
zaura rf wireless library programmer?s reference manual RM006003-1011 console global variables 63 the remaining three tokens reference the parameters 1 , 2 and 3 , respec- tively. if a parameter must contain spaces, enclose the parameter within spaces. the command line test "this is one token" 2 3 also contains 4 tokens, with the first parameter being this is one token . after parsing the command line into tokens, zaura_rf_processcmdline api compares the name command submitted (referenced by pzaura_rf_tokens[0]) to the current set of shell commands. if a match is found, the corresponding function po inter is called. otherwise, an error message is displayed on the console. if the entered shell comman d corresponds to a user-d efined function, then the application is responsible for pr ocessing the command. exactly how the application processes this comm and is application-dependent. the remainder of this section describes th e zaura rf shell global variables and api functions available to user-defined shell commands. console global variables table 13 describes the types of co nsole variables employed by the zaura rf wireless shell api. table 13. console global variables variable name type description zaura_rf_numtokens uint8 used by shell rout ines to determine the number of space- separated strings (i.e., tokens) within the console command. for example, the command line mycmd has 3 parameters contains 4 tokens. if a token must include spaces, enclose it in quotation marks. the line this is a single token contains just one token. the maximum number of tokens that can be supported is zaura_rf_shell_max_tokens (currently defined as 5). pzaura_rf_token[max_t okens] char * an array of pointers referencing the null-terminated string of characters comprising the token.
zaura rf wireless library programmer?s reference manual zaura rf wireless shell api reference RM006003-1011 64 zaura rf wireless shell api descriptions the section that follows describes th e console utility functions employed by the zaura rf wireless shell api. zaura_rf_uarteol uint8 this flag is set to true after the shell library detects a carriage return received on uart 0. applications can use this flag to decide when to call the zaura_rf_shellprocesscmdline api. zaura_rf_uartavail uint8 yields the number of characters in the console buffer waiting to be processed. table 13. console global variables variable name type description
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura_rf_processcommandline() 65 zaura_rf_processcommandline() description the zaura_rf_processcommandline api handles the processing the console input after a user has pressed the carriage return. an appli- cation should call this routine shortly after the zaura_rf_uarteol flag is set to true, which indicates that the console operator has pressed the enter key. the application is free to defer processing of the command line until more important operations have completed. syntax void processcommandline( void ) parameters this function does not have any parameters. returns none. example /* * wait for end of line character before processing ?
zaura rf wireless library programmer?s reference manual zaura rf wireless shell api reference RM006003-1011 66 zaura_rf_shelladdcmd description the zaura_rf_shelladdcmd function is used to add a nondefault command to the zaura rf shell. the shell can accommodate a maximum of 30 commands, of which 7 are reserved to hold the default set of shell commands. consequently, 23 slots are available for adding optional zaura rf shell commands or user-defined commands. syntax zaura_rf_status zaura_rf_shelladdcmd( char * pname, shell_cmd pfunc) parameters the available library shell comm ands are described in table 14. pname a pointer to a null-terminated string containing the token for the user to enter into the console to identify this command. pfunc the name of the function that implements the shell command. the function prototype must be: void pfunc( void ); table 14. library shell commands shell command (pname) function pointer (pfunc) use for addr zaura_rf_shellcmdaddr get/set the local zaura rf wireless module station address. ch zaura_rf_shellcmdchannel get/set the current zaura rf wireless module channel. data zaura_rf_shellcmddata enter data mode (exits local console mode). dst zaura_rf_shellcmddst get/set default remote target address. echo zaura_rf_shellcmdecho initiates ping-pong test between 2 nodes. filter zaura_rf_shellcmdfilter get/set the zaura rf wireless module receive filter.
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura_rf_shelladdcmd 67 returns if there was room to add the command, then zaura_rf_success is returned; otherwise, zaura_rf_failure is returned. example void ipo zaura_rf_shellcmdipo ge t/set system internal precision oscillator frequency. nid zaura_rf_shellcmdnid get/set the zaura rf wireless module network identifier. pa zaura_rf_shellcmdpa initiates transmission of preamble pattern. per zaura_rf_shellcmdper initiate transmission of a burst of 100 packets (use with peer running 'rx' command). port zaura_rf_shellcmdport modifies a gpio port output pin. pwr zaura_rf_shellcmdpwr get/set the zaura rf wireless module transmit power level. reboot zaura_rf_shellsoftreset initiates por reset. rssi zaura_rf_shellcmdrssi displays rssi of the current rf channel. rx zaura_rf_shellcmdrx places the radio in receive mode waiting for a burst of 100 packets from remote peer running 'per' command. sleep zaura_rf_shellcmdsleep places the zaura rf wireless module node in a low power mode until a console character is received or a push button activated. stats zaura_rf_shellcmdstats displays packet level statistics. tx zaura_rf_shellcmdtx transmits one or more data packets. uecho zaura_rf_shellcmdzaura_rf_ uartecho enable/disable local echoing of console input. table 14. library shell commands shell command (pname) function pointer (pfunc) use for
zaura rf wireless library programmer?s reference manual zaura rf wireless shell api reference RM006003-1011 68 initshell(void) { zaura_rf_shelladdcmd( "addr", zaura_rf_shellcmdaddr ); zaura_rf_shelladdcmd( "ch", zaura_rf_shellcmdchannel ); zaura_rf_shelladdcmd( "data", zaura_rf_shellcmddata ); zaura_rf_shelladdcmd( "dst", zaura_rf_shellcmddst ); zaura_rf_shelladdcmd( "echo", zaura_rf_shellcmdecho ); zaura_rf_shelladdcmd( "filter",zaura_rf_shellcmdfilter ); zaura_rf_shelladdcmd( "ipo", zaura_rf_shellcmdipo ); zaura_rf_shelladdcmd( "nid", zaura_rf_shellcmdnid ); zaura_rf_shelladdcmd( "pa", zaura_rf_shellcmdpa ); zaura_rf_shelladdcmd( "per", zaura_rf_shellcmdper ); zaura_rf_shelladdcmd( "port", zaura_rf_shellcmdport ); zaura_rf_shelladdcmd( "pwr", zaura_rf_shellcmdpwr ); zaura_rf_shelladdcmd( "reboot",zaura_rf_softreset ); zaura_rf_shelladdcmd( "rssi", zaura_rf_shellcmdrssi ); zaura_rf_shelladdcmd( "rx", zaura_rf_shellcmdrx ); zaura_rf_shelladdcmd( "sleep", zaura_rf_shellcmdsleep ); zaura_rf_shelladdcmd( "stats", zaura_rf_shellcmdstats ); zaura_rf_shelladdcmd( "tx", zaura_rf_shellcmdtx ); zaura_rf_shelladdcmd( "uecho", zaura_rf_shellcmduartecho ); }
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura_rf_shellatox 69 zaura_rf_shellatox description the zaura_rf_shellatox function replaces the ascii string pointed to by pdata with a converted hexadecimal value. no error check is performed on the string. it is assumed that the string contains only numbers from 0?9 and a?f (or a?f). if there are other characters, the result is unpredictable. this api overwrites the pdata buffer. syntax uint8 zaura_rf_shellatox(char * pdata) parameters returns number of characters converted. example uint8 data; /* * convert ascii parameter to hexadecimal value. */ zaura_rf_shellatox( pzaura_rf_token[1] ); data = (uint8)*pzaura_rf_token[1]; pdata a pointer to the hexadecimal characters to be converted to a hexadec- imal value.
zaura rf wireless library programmer?s reference manual zaura rf wireless shell api reference RM006003-1011 70 zaura_rf_shellstricmp description the zaura_rf_shellstricmp function performs a case insensitive comparison on the characters in strings s1 and s2. syntax int8 zaura_rf_shellstricmp(char * s1, char * s2) parameters returns 0 if identical (regardless of case), a signed integer if they are unequal, a positive number if s1 is more than s2, and a negative number if s2 is more than s1. example if( zaura_rf_shellstricmp("mycmd", pzaura_rf_token[0]) == 0 ) { // operator entered a command like "mycmd" or "mycmd" } s1 a pointer to the first string to compare. s2 a pointer to the sec ond string to compare.
zaura rf wireless library programmer?s reference manual RM006003-1011 zaur a_rf_shellhexdump 71 zaura_rf_shellhexdump description this function displays len bytes of ram (in hexadecimal format) starting at the memory location referenced by hdata on the console. syntax void zaura_rf_shellhexdump(handle hdata, uint8 len) parameters returns none. example uint8 data[4] = {0x11,0xbb,0xcc,0xdd}; /* * display the data array on the console in hex */ zaura_rf_shellhexdump( data, 4 ); hdata a pointer to the bytes to be displayed (in hexadecimal format). len the number of bytes that are valid in hdata.
zaura rf wireless library programmer?s reference manual zaura rf wireless shell api reference RM006003-1011 72 zaura_rf_shellcontrol description the zaura_rf_shellcontrol function enables and disables the con- sole. to prevent messages from being displayed on the console, you can disable the console by passing a 0 in the parameter. to re-enable pass a non-zero value. disabling the console will block the operation of the data and remote console commands. syntax void zaura_rf_shellcontrol(uint8 enable) parameters returns none. example /* * disable console output */ zaura_rf_shellcontrol( 0 ); enable when this parameter is set to true (nonzero), the console will be enabled. set to false (0) to disable it.
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura_rf_shellprintf 73 zaura_rf_shellprintf description the zaura_rf_shellprintf prints a formatted string on the console. the format string defines what the output should look like and includes special characters as placeholders for numbers and characters that are passed to the function as arguments. this is a scaled down version of the standard printf(). syntax zaura_rf_status zaura_rf_shellprintf(const char * format, ?) parameters the format string can co ntain any of the conversion flags and argument types listed in the following table. format the format string for the list of arguments. ? a list of 0 or more arguments to be printed on the console, using the format string. conversion flag argument type output %c unsigned 8-bit integer ascii representation of the 1 byte hexadecimal input value. input should be between 0x20 and 0x7f . %d signed 16-bit integer ?32768 to 32767. %ld signed 32-bit integer ?2147483648 to 2147483647. %u unsigned 16-bit integer 0 to 65535. %lu unsigned 32-bit integer 0 to 4,294,967,295. %x 16-bit hex value 0 to ffff (always upper case). %lx 32-bit hex value 0 to ffffffff (always upper case). %s character string ascii representation of the character string. %% none add the '%' sign to the output.
zaura rf wireless library programmer?s reference manual zaura rf wireless shell api reference RM006003-1011 74 additional conversion fl ag formatting informatio n can be added between the '%' symbol and the letter that fo llows it. this extra formatting can be represented by any of the symbols defined in the following table. conversion flag meaning description 1 to 9 minimum field width (1 to 9 characters) conversion is left-padded with spaces until the output reaches the specified minimum field width. can be combined with '0' conversion flag to pad with leading zeros instead of spaces (for 'd', 'u' and 'x' numeric conversions). unlike standard printf only a single-digit field width can be specified. * minimum field width (1 to 255 characters) used to specify minimum field widths larger than 9 characters. can be combined with '0' conversion flag to pad with leading zeros instead of spaces (for 'd', 'u' and 'x' numeric conversions). the field width is specified in the variable arguments list. 0 zero left-pad used with either of the previous two flags to specify that left padding for numeric conversions should use leading zeros instead of spaces. has no effect is used with 'c' or 's' conversion flags. - left justify by default zaura_rf _shellprintf will right justify the output if a minimum field width is specified and the converted value is narrow than the specified minimum. this flag cause the output to be left justified (right-padded). with left justification, the pad character is always a space (' '), even if the 0 flag is specified.
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura_rf_shellprintf 75 returns example /* * displays "data: 0010" */ zaura_rf_shellprintf( "data: %04x\r\n", 16 ); /* * displays "data: 0x10" */ zaura_rf_shellprintf( "data: %#04x\r\n", 16 ); /* * displays "data: +00000000016" */ zaura_rf_shellprintf( "data: %+*0d\r\n", 12, 16 ); + show sign by default zaura_rf_shellprintf will display a leading '-' when used with signed conversion ('d' or 'ld') and no sign indicator for positive values. this flag causes zaura_rf_shellprintf to display a leading '+' for positive signed values. #h e x 0x prefix causes con_print to prefix hexadecimal values (' x ' and ' lx ') with ' 0x ' ignored on non-hexadecimal formats. unlike printf zaura_rf_shellprintf will display a leading 0x when used to display the value 0. zaura_rf_success if the function wa s able to comple te the request. zaura_rf_failure if the function was unable to write to the console, such as if it was disabled. conversion flag meaning description
zaura rf wireless library programmer?s reference manual zaura rf wireless shell api reference RM006003-1011 76
zaura rf wireless library programmer?s reference manual RM006003-1011 timer api functions 77 timer api functions the zaura rf wireless library uses timer 1 for internal operations; applications must not use timer 1. these apis expose generic timer functions based off of the external 32 .768 khz crystal. the tick period is approximately 30.5 s. zaura_rf_tickdelay description the zaura_rf_tickdelay implements a delay of delay * 30.5s. the maximum delay is approximately 1 second ( 0x7fff ). control is not returned to the caller until the specified delay has expired. syntax void zaura_rf_tickd elay(uint16 delay) parameters returns none. see also zaura_rf_ms_to_ticks example /* * wait 10 timer ticks (approximately 305 s) */ zaura_rf_tickdelay( 10 ); delay the number of ticks to delay.
zaura rf wireless library programmer?s reference manual timer api functions RM006003-1011 78 zaura_rf_ms_to_ticks description the zaura_rf_ms_to_ticks macro converts milliseconds into ticks. syntax uint16 zaura_rf_ms_to_ticks(uint16 delay_ms) parameters returns the number of ticks that delay_ms converts to. example uint16 ticks; /* * convert 30ms to the corresponding number of timer ? delay_ms the duration of time it takes, in milliseconds, to convert to ticks.
zaura rf wireless library programmer?s reference manual RM006003-1011 zaura_rf_readtimer 79 zaura_rf_readtimer description this routine returns a value between 0x0001 and 0x8000 , repre- senting the current tick count of the zaura rf timer. syntax uint16 zaura_rf_readtimer( void ); parameters none. returns a 16-bit tick count of the zaura rf timer (frequency approximately 32.768 khz). example uint16 tickcount; tickcount = zaura_rf_readtimer();
zaura rf wireless library programmer?s reference manual timer api functions RM006003-1011 80 zaura_rf_getticks description the zaura_rf_getticks function is used to measure short intervals (less than 1 second) instead of wasting cpu cycles in a synchronous delay loop. this allows the application to perform simple tasks while waiting for some other operation to complete. syntax uint16 zaura_rf_getticks(uint16 start) parameters returns 16-bit count of the number of timer ticks have elapsed since the inter- val began. (max: 0x7fff ). example /* * check for console input for up to 700ms. */ uint16 start = zaura_rf_readtimer(); while( zaura_rf_getticks(start) < zaura_rf_ms_to_ticks(700) ) { if( zaura_rf_uarteol ) { zaura_rf_processcmdline(); break; } } start a 16-bit timestamp indicating the beginning of an interval.
zaura rf wireless library programmer?s reference manual RM006003-1011 appendix a. project information 81 appendix a. project information this section of the document discusses the user code space within flash memory and explains how to create an application w ith the zaura rf wireless module using the zaura rf wireless module and shell librar- ies and zilog developer studio. memory map the default zaura rf wireless module demo project uses approxi- mately 18 kb of flash memory. almost half of the code space is used by the shell library (estimated at 8 kb ). applications that use the zaura rf wireless shell library are unlikely to require all of the extra console commands available in the library. the zaura rf wireless library uses the last page of flash memory, in the address range 0x5e00 to 0x5fff , for storing parameters. application programs that use the zaura rf wire less module libraries must not use any flash memory above 0x5dff . the zaura rf library uses all 1kb of available pram for packet buf- fers. application programs must not attempt to use pram for any pur- pose. z8f2480 mcu peripherals the zaura rf wireless library uses the following z8f2480 mcu peripherals: uart0, espi and timer1. these peripherals must not be used by applications linking to the zaura rf wireless library. table 15 shows the z8f2480 mcu?s available gpio pins and their usage. all other pins are used by the zaura rf wireless library and cannot be used for any other purpose.
zaura rf wireless library programmer?s reference manual appendix a. project information RM006003-1011 82 table 15. z8f2480 mcu gpios port pin setting usage port a 0 out_0 can be used by the application for any purpose. 1 out_0 can be used by the application for any purpose. 6 out_0 can be used by the application for any purpose. 7 out_0 can be used by the application for any purpose. port b 0 out_0 can be used by the application for any purpose. 1 out_0 can be used by the application for any purpose. 2 out_0 can be used by the application for any purpose. 3 out_0 can be used by the application for any purpose. 4 out_0 can be used by the application for any purpose. 5 out_0 can be used by the application for any purpose. port d 0 out_0 reset/ gpio. 1 in_irq sw2. 2 in_irq sw1. 3 out_0 unused/ uart 1 cts. 4 out_0 unused/ uart 1 rx. 5 out_0 unused/ uart 1 tx. 6 out_0 unused/ uart 1 rts. 7 out_0 can be used by the application for any purpose.
zaura rf wireless library programmer?s reference manual RM006003-1011 using zds ii to create an application 83 using zds ii to create an application the zaura rf wireless module and shell libraries are designed to be used with zds ii for encore! version 5.0. the library installs the following folders: for purposes of readability, the base folder will be referenced as zaura_rf_wireless , although it may be diff erent on your installation. port e 0 out zaura rf wireless library test point. 1 out zaura rf wireless library test point. 2 out_0 can be used by the application for any purpose. 3in uart 0 cts. 4 out uart 0 rts. 5 out led 1. 6 out led 2. conf contains the configur ation files, including zaura_rf_conf.c . typically, you will want to copy these file s to your project folder if you will be making any changes. demo this folder contai ns the demo project that is loaded on the kits at the factory. this also is an example of how to us e the libraries. you can use this as a starting point for your application. docs this folder contains the demo information and this programmer?s reference manual. inc this folder contains the header fi les necessary for using the libraries. lib this folder contains th e libraries in object form , to be linked with your application. table 15. z8f2480 mcu gpios (continued) port pin setting usage
zaura rf wireless library programmer?s reference manual appendix a. project information RM006003-1011 84 create an application create a new zaura rf wireless modu le application with zilog devel- oper studio by observing the following procedure. the easiest way to create an application is to copy the demo project to a new folder and use that fold er as your starting point. 1. make a new folder in the root of the zaura_rf_wireless installa- tion folder that will be a peer to the demo folder. 2. copy the zaura_rf_demo.zdsproj file from the demo folder into the new folder (rename the pr oject file if appropriate). 3. launch the zds ii ? z8 encore! 5.0.0 program and select the file open project menu option. navigate to the location of the project folder created in step 1 and double -click the project file created in this folder in step 2. the default name will be zaura_rf_demo.zdsproj unless you used a different project name in step 2. 4. remove all four source files from the project by right-clicking each file listed under standard project files and selecting the remove selected file(s) pop-up menu option. 5. copy the original zaura_rf_conf.c , gpioconfig.c and reset.asm files from the zaura_rf_wireless\conf folder to the new project folder. 6. add the three files copied in step 5 to the project by right-clicking standard project files , then selecting the add files to project... pop-up menu option. be sure to navigate to the project folder created in step 1, then the three files you copied in step 5. 7. create a file named main.c in the project folder that you created in step 1. note:
zaura rf wireless library programmer?s reference manual RM006003-1011 create an application 85 users that prefer to start from a working project can simply copy main.c from the demo folder to the project fo lder created in step 1. in this instance, skip ahead to step 10. ? ? users that prefer to create a new main.c file can select the file : new file menu option and continue with step 8. in this instance, an empty win- dow will open in zds ii in which you can start typing code. 8. copy and paste the following text into the empty window (or enter it manually): void main( void ) { } 9. select the file : save as menu option. a dialog box will appear, prompting you for a name to give the new file. enter main.c in the file name: text field. 10. add this new main.c file to the project us ing the same process you used in step 6. 11. your project is complete! you can now begin building your applica- tion. note:
zaura rf wireless library programmer?s reference manual appendix a. project information RM006003-1011 86
zaura rf wireless library programmer?s reference manual RM006003-1011 customer support 87 customer support to share comments, get your technical questions answered, or report issues you may be experiencing with our products, please visit zilog?s technical support page at http://support.zilog.com . to learn more about this product, fi nd additional documentation, or to discover other facets about zilog prod uct offerings, please visit the zilog knowledge base at http://zilog.com/kb or consider participating in the zilog forum at http://zilog.com/forum . this publication is subject to replac ement by a later edition. to determine whether a later edition exists, please visit the zilog website at http:// www.zilog.com .

▲Up To Search▲

Price & Availability of RM0060

	To Download RM0060 Datasheet File
If you can't view the Datasheet, Please click here to try to view without PDF Reader .